home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996…eptember: Technology Seed / Mac Tech Seed Sep '96 / Mac Tech Seed Sep '96.toast / mac / QuickDraw 3D 1.5d7 / Interfaces / QD3DView.h < prev    next >
Encoding:
C/C++ Source or Header  |  1996-08-23  |  13.6 KB  |  425 lines  |  [TEXT/R*ch]
  1. /******************************************************************************
  2.  **                                                                             **
  3.  **     Module:        QD3DView.h                                                 **
  4.  **                                                                             **
  5.  **                                                                             **
  6.  **     Purpose:     View types and routines                                     **
  7.  **                                                                             **
  8.  **                                                                             **
  9.  **                                                                             **
  10.  **     Copyright (C) 1992-1996 Apple Computer, Inc.  All rights reserved.     **
  11.  **                                                                             **
  12.  **                                                                             **
  13.  *****************************************************************************/
  14. #ifndef QD3DView_h
  15. #define QD3DView_h
  16.  
  17. #if defined(PRAGMA_ONCE) && PRAGMA_ONCE
  18.     #pragma once
  19. #endif  /*  PRAGMA_ONCE  */
  20.  
  21. #include "QD3DStyle.h"
  22. #include "QD3DSet.h"
  23.  
  24. #if defined(THINK_C) || defined(__SC__)
  25.     #pragma options(!pack_enums, !align_arrays)
  26.     #pragma SC options align=power
  27. #elif defined(__MWERKS__)
  28.     #pragma enumsalwaysint on
  29.     #pragma align_array_members off
  30.     #pragma options align=native
  31. #elif defined(__PPCC__)
  32.     #pragma options align=power
  33. #elif defined(__xlc) || defined(__xlC) || defined(__xlC__) || defined(__XLC121__)
  34.     #pragma options enum=int
  35. #endif
  36.  
  37. #ifdef __cplusplus
  38. extern "C" {
  39. #endif    /* __cplusplus */
  40.  
  41.  
  42. /******************************************************************************
  43.  **                                                                             **
  44.  **                        View Type Definitions                                 **
  45.  **                                                                             **
  46.  *****************************************************************************/
  47.  
  48. typedef enum TQ3ViewStatus {
  49.     kQ3ViewStatusDone,
  50.     kQ3ViewStatusRetraverse,
  51.     kQ3ViewStatusError,
  52.     kQ3ViewStatusCancelled
  53. } TQ3ViewStatus;
  54.  
  55. /******************************************************************************
  56.  **                                                                             **
  57.  **                        Default Attribute Set                                 **
  58.  **                                                                             **
  59.  *****************************************************************************/
  60.  
  61. #define kQ3ViewDefaultAmbientCoefficient    1.0
  62. #define kQ3ViewDefaultDiffuseColor            0.5, 0.5, 0.5
  63. #define kQ3ViewDefaultSpecularColor            0.5, 0.5, 0.5
  64. #define kQ3ViewDefaultSpecularControl        4.0
  65. #define kQ3ViewDefaultTransparency            1.0, 1.0, 1.0
  66. #define kQ3ViewDefaultHighlightColor        1.0, 0.0, 0.0
  67.  
  68. #define kQ3ViewDefaultSubdivisionMethod        kQ3SubdivisionMethodScreenSpace
  69. #define kQ3ViewDefaultSubdivisionC1            20.0
  70. #define kQ3ViewDefaultSubdivisionC2            20.0
  71.  
  72.  
  73. /******************************************************************************
  74.  **                                                                             **
  75.  **                            View Routines                                     **
  76.  **                                                                             **
  77.  *****************************************************************************/
  78.  
  79. QD3D_EXPORT TQ3ViewObject Q3View_New(
  80.     void);
  81.  
  82. QD3D_EXPORT TQ3Status Q3View_Cancel(
  83.     TQ3ViewObject        view);
  84.  
  85. /******************************************************************************
  86.  **                                                                             **
  87.  **                        View Rendering routines                                 **
  88.  **                                                                             **
  89.  *****************************************************************************/
  90.  
  91. QD3D_EXPORT TQ3Status Q3View_SetRendererByType(
  92.     TQ3ViewObject         view,
  93.     TQ3ObjectType         type);
  94.     
  95. QD3D_EXPORT TQ3Status Q3View_SetRenderer(
  96.     TQ3ViewObject         view,
  97.     TQ3RendererObject    renderer);
  98.  
  99. QD3D_EXPORT TQ3Status Q3View_GetRenderer(
  100.     TQ3ViewObject        view,
  101.     TQ3RendererObject    *renderer);
  102.     
  103. QD3D_EXPORT TQ3Status Q3View_StartRendering(
  104.     TQ3ViewObject         view);
  105.     
  106. QD3D_EXPORT TQ3ViewStatus Q3View_EndRendering(
  107.     TQ3ViewObject         view);
  108.     
  109. QD3D_EXPORT TQ3Status Q3View_Flush(
  110.     TQ3ViewObject        view);
  111.     
  112. QD3D_EXPORT TQ3Status Q3View_Sync(
  113.     TQ3ViewObject        view);
  114.  
  115. /******************************************************************************
  116.  **                                                                             **
  117.  **                        View/Bounds/Pick routines                             **
  118.  **                                                                             **
  119.  *****************************************************************************/
  120.  
  121. QD3D_EXPORT TQ3Status Q3View_StartBoundingBox(
  122.     TQ3ViewObject        view,
  123.     TQ3ComputeBounds    computeBounds);
  124.  
  125. QD3D_EXPORT TQ3ViewStatus Q3View_EndBoundingBox(
  126.     TQ3ViewObject        view,
  127.     TQ3BoundingBox        *result);
  128.  
  129. QD3D_EXPORT TQ3Status Q3View_StartBoundingSphere(
  130.     TQ3ViewObject        view,
  131.     TQ3ComputeBounds    computeBounds);
  132.  
  133. QD3D_EXPORT TQ3ViewStatus Q3View_EndBoundingSphere(
  134.     TQ3ViewObject        view,
  135.     TQ3BoundingSphere    *result);
  136.  
  137. QD3D_EXPORT TQ3Status Q3View_StartPicking(
  138.     TQ3ViewObject        view,
  139.     TQ3PickObject        pick);
  140.  
  141. QD3D_EXPORT TQ3ViewStatus Q3View_EndPicking(
  142.     TQ3ViewObject        view);
  143.  
  144.  
  145. /******************************************************************************
  146.  **                                                                             **
  147.  **                            View/Camera routines                             **
  148.  **                                                                             **
  149.  *****************************************************************************/
  150.  
  151. QD3D_EXPORT TQ3Status Q3View_GetCamera(
  152.     TQ3ViewObject        view,
  153.     TQ3CameraObject        *camera);
  154.  
  155. QD3D_EXPORT TQ3Status Q3View_SetCamera(
  156.     TQ3ViewObject        view,
  157.     TQ3CameraObject        camera);
  158.  
  159. /******************************************************************************
  160.  **                                                                             **
  161.  **                            View/Lights routines                             **
  162.  **                                                                             **
  163.  *****************************************************************************/
  164.  
  165. QD3D_EXPORT TQ3Status Q3View_SetLightGroup(
  166.     TQ3ViewObject        view,
  167.     TQ3GroupObject        lightGroup);
  168.  
  169. QD3D_EXPORT TQ3Status Q3View_GetLightGroup(
  170.     TQ3ViewObject        view,
  171.     TQ3GroupObject        *lightGroup);
  172.  
  173. /******************************************************************************
  174.  **                                                                             **
  175.  **                                Idle Method                                     **
  176.  **                                                                             **
  177.  *****************************************************************************/
  178. /*
  179.  *    The idle methods allow the application to register callback routines 
  180.  *    which will be called by the view during especially long operations.
  181.  *
  182.  *    The idle methods may also be used to interrupt long renderings or
  183.  *    traversals.  Inside    the idler callback the application can check for
  184.  *    Command-Period, Control-C or clicking a "Cancel" button or whatever else
  185.  *    may be used to let the user interrupt rendering.    
  186.  *
  187.  *    It is NOT LEGAL to call QD3D routines inside an idler callback.
  188.  *
  189.  *    Return kQ3Failure to cancel rendering, kQ3Success to continue. Don't
  190.  *    bother posting an error.
  191.  *
  192.  *    Q3View_SetIdleMethod registers a callback that can be called
  193.  *    by the system during rendering.  Unfortunately there is no way yet
  194.  *    to set timer intervals when you want to be called.  Basically, it is
  195.  *    up to the application's idler callback to check clocks to see if you
  196.  *    were called back only a millisecond ago or an hour ago!
  197.  *
  198.  *    Q3View_SetIdleProgressMethod registers a callback that also gives
  199.  *    progress information. This information is supplied by the renderer, and
  200.  *    may or may not be based on real time.
  201.  *
  202.  *    If a renderer doesn't support the progress method, your method will be
  203.  *    called with current == 0 and completed == 0.
  204.  *    
  205.  *    Otherwise, you are GUARANTEED to get called at least 2 or more times:
  206.  *    
  207.  *    ONCE            idleMethod(view, 0, n)        -> Initialize, Show Dialog
  208.  *    zero or more    idleMethod(view, 1..n-1, n) -> Update progress
  209.  *    ONCE            idleMethod(view, n, n)        -> Exit, Hide Dialog
  210.  *    
  211.  *    "current" is guaranteed to be less than or equal to "completed"
  212.  *    "completed" may change values, but current/complete always indicates
  213.  *    the degree of completion.
  214.  *
  215.  *    The calling conventions aid in managing any data associated with a 
  216.  *    progress user interface indicator.
  217. */
  218.  
  219. typedef TQ3Status (*TQ3ViewIdleMethod)(
  220.     TQ3ViewObject        view,
  221.     const void            *idlerData);
  222.  
  223. typedef TQ3Status (*TQ3ViewIdleProgressMethod)(
  224.     TQ3ViewObject        view,
  225.     const void            *idlerData,
  226.     unsigned long        current,
  227.     unsigned long        completed);
  228.  
  229. QD3D_EXPORT TQ3Status Q3View_SetIdleMethod(
  230.     TQ3ViewObject        view,
  231.     TQ3ViewIdleMethod    idleMethod,
  232.     const void             *idleData);
  233.  
  234. QD3D_EXPORT TQ3Status Q3View_SetIdleProgressMethod(
  235.     TQ3ViewObject                view,
  236.     TQ3ViewIdleProgressMethod    idleMethod,
  237.     const void                     *idleData);
  238.  
  239. /******************************************************************************
  240.  **                                                                             **
  241.  **                                EndFrame Method                                 **
  242.  **                                                                             **
  243.  *****************************************************************************/
  244.  
  245. /*
  246.  *    The end frame method is an alternate way of determining when an
  247.  *    asynchronous renderer has completed rendering a frame. It differs from
  248.  *    Q3View_Sync in that notification of the frame completion is the opposite
  249.  *    direction. 
  250.  *    
  251.  *    With Q3View_Sync the application asks a renderer to finish rendering
  252.  *    a frame, and blocks until the frame is complete.
  253.  *    
  254.  *    With the EndFrame method, the renderer tells the application that is has
  255.  *    completed a frame.
  256.  *
  257.  *    If "Q3View_Sync" is called BEFORE this method has been called, this
  258.  *    method will NOT be called ever.
  259.  *    
  260.  *    If "Q3View_Sync" is called AFTER this method has been called, the
  261.  *    call will return immediately (as the frame has already been completed).
  262.  */
  263.  
  264. typedef void (*TQ3ViewEndFrameMethod)(
  265.     TQ3ViewObject            view,
  266.     void                    *endFrameData);
  267.  
  268. QD3D_EXPORT TQ3Status Q3View_SetEndFrameMethod(
  269.     TQ3ViewObject            view,
  270.     TQ3ViewEndFrameMethod    endFrame,
  271.     void                     *endFrameData);
  272.  
  273. /******************************************************************************
  274.  **                                                                             **
  275.  **                            Push/Pop routines                                 **
  276.  **                                                                             **
  277.  *****************************************************************************/
  278.  
  279. QD3D_EXPORT TQ3Status Q3Push_Submit(
  280.     TQ3ViewObject     view);
  281.  
  282. QD3D_EXPORT TQ3Status Q3Pop_Submit(
  283.     TQ3ViewObject     view);
  284.  
  285.  
  286. /******************************************************************************
  287.  **                                                                             **
  288.  **        Check if bounding box is visible in the viewing frustum.  Transforms **
  289.  **        the bbox by the current local_to_world transformation matrix and     **
  290.  **        does a clip test to see if it lies in the viewing frustum.             **
  291.  **        This can be used by applications to cull out large chunks of scenes     **
  292.  **        that are not going to be visible.                                     **
  293.  **                                                                             **
  294.  **        The default implementation is to always return kQ3True.  Renderers     **
  295.  **        may override this routine however to do the checking.                 **
  296.  **                                                                             **
  297.  *****************************************************************************/
  298.  
  299. QD3D_EXPORT TQ3Boolean Q3View_IsBoundingBoxVisible(
  300.     TQ3ViewObject            view,
  301.     const TQ3BoundingBox    *bbox);
  302.  
  303.  
  304. /******************************************************************************
  305.  **                                                                             **
  306.  **                            DrawContext routines                             **
  307.  **                                                                             **
  308.  *****************************************************************************/
  309.  
  310. QD3D_EXPORT TQ3Status Q3View_SetDrawContext(
  311.     TQ3ViewObject             view,
  312.     TQ3DrawContextObject    drawContext);
  313.  
  314. QD3D_EXPORT TQ3Status Q3View_GetDrawContext(
  315.     TQ3ViewObject             view,
  316.     TQ3DrawContextObject    *drawContext);
  317.  
  318.  
  319. /******************************************************************************
  320.  **                                                                             **
  321.  **                            Graphics State routines                             **
  322.  **                                                                             **
  323.  ** The graphics state routines can only be called while rendering (ie. in     **
  324.  ** between calls to start and end rendering calls).  If they are called     **
  325.  ** outside of a rendering loop, they will return with error.                 **
  326.  **                                                                             **
  327.  *****************************************************************************/
  328.   
  329. /******************************************************************************
  330.  **                                                                             **
  331.  **                            Transform routines                                 **
  332.  **                                                                             **
  333.  *****************************************************************************/
  334.  
  335. QD3D_EXPORT TQ3Status Q3View_GetLocalToWorldMatrixState(
  336.     TQ3ViewObject        view,
  337.     TQ3Matrix4x4        *matrix);
  338.         
  339. QD3D_EXPORT TQ3Status Q3View_GetWorldToFrustumMatrixState(
  340.     TQ3ViewObject        view,
  341.     TQ3Matrix4x4        *matrix);
  342.         
  343. QD3D_EXPORT TQ3Status Q3View_GetFrustumToWindowMatrixState(
  344.     TQ3ViewObject        view,
  345.     TQ3Matrix4x4        *matrix);
  346.     
  347.  
  348. /******************************************************************************
  349.  **                                                                             **
  350.  **                            Style state routines                             **
  351.  **                                                                             **
  352.  *****************************************************************************/
  353.  
  354. QD3D_EXPORT TQ3Status Q3View_GetBackfacingStyleState(
  355.     TQ3ViewObject            view,
  356.     TQ3BackfacingStyle        *backfacingStyle);
  357.  
  358. QD3D_EXPORT TQ3Status Q3View_GetInterpolationStyleState(
  359.     TQ3ViewObject            view,
  360.     TQ3InterpolationStyle    *interpolationType);
  361.  
  362. QD3D_EXPORT TQ3Status Q3View_GetFillStyleState(
  363.     TQ3ViewObject            view,
  364.     TQ3FillStyle            *fillStyle);
  365.  
  366. QD3D_EXPORT TQ3Status Q3View_GetHighlightStyleState(
  367.     TQ3ViewObject            view,
  368.     TQ3AttributeSet            *highlightStyle);
  369.  
  370. QD3D_EXPORT TQ3Status Q3View_GetSubdivisionStyleState(
  371.     TQ3ViewObject            view,
  372.     TQ3SubdivisionStyleData    *subdivisionStyle);
  373.  
  374. QD3D_EXPORT TQ3Status Q3View_GetOrientationStyleState(
  375.     TQ3ViewObject            view,
  376.     TQ3OrientationStyle        *fontFacingDirectionStyle);
  377.  
  378. QD3D_EXPORT TQ3Status Q3View_GetReceiveShadowsStyleState(
  379.     TQ3ViewObject            view,
  380.     TQ3Boolean                *receives);
  381.  
  382. QD3D_EXPORT TQ3Status Q3View_GetPickIDStyleState(
  383.     TQ3ViewObject            view,
  384.     unsigned long            *pickIDStyle);
  385.     
  386. QD3D_EXPORT TQ3Status Q3View_GetPickPartsStyleState(
  387.     TQ3ViewObject            view,
  388.     TQ3PickParts            *pickPartsStyle);
  389.  
  390. /******************************************************************************
  391.  **                                                                             **
  392.  **                        Attribute state routines                             **
  393.  **                                                                             **
  394.  *****************************************************************************/
  395.  
  396. QD3D_EXPORT TQ3Status Q3View_GetDefaultAttributeSet(
  397.     TQ3ViewObject        view,
  398.     TQ3AttributeSet        *attributeSet);
  399.  
  400. QD3D_EXPORT TQ3Status Q3View_SetDefaultAttributeSet(
  401.     TQ3ViewObject        view,
  402.     TQ3AttributeSet        attributeSet);
  403.  
  404.  
  405. QD3D_EXPORT TQ3Status Q3View_GetAttributeSetState(
  406.     TQ3ViewObject         view,
  407.     TQ3AttributeSet        *attributeSet);
  408.  
  409. QD3D_EXPORT TQ3Status Q3View_GetAttributeState(
  410.     TQ3ViewObject         view,
  411.     TQ3AttributeType    attributeType,
  412.     void                *data);
  413.  
  414. #ifdef __cplusplus
  415. }
  416. #endif    /* __cplusplus */
  417.  
  418. #if defined(__MWERKS__)
  419.     #pragma enumsalwaysint reset
  420. #elif defined(__xlc) || defined(__xlC) || defined(__xlC__) || defined(__XLC121__)
  421.     #pragma options enum=reset
  422. #endif
  423.  
  424. #endif  /*  QD3DView_h  */
  425.